home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
TPUG - Toronto PET Users Group
/
TPUG Users Group CD
/
TPUG Users Group CD.iso
/
AMIGA
/
AMICUS
/
AMICUS04.ADF
/
text
/
consoleIO.txt
< prev
next >
Wrap
Text File
|
1985-12-04
|
57KB
|
1,979 lines
Chapter 1
Console Device
This chapter describes how you do console (keyboard and screen)
input and output on the Amiga. The console device acts like an
enhanced ASCII terminal. It obeys many of the standard ANSI
sequences as well as additional special sequences unique to the
Amiga.
1.1. INTRODUCTION
Console I/O is tied closely to the Amiga Intuition interface; a
console must be tied to a window that is already opened. From
the Window data structure, the console device determines how many
characters it can display on a line and how many lines of text it
can display in a window without clipping at any edge.
You can open the console device many times, if you wish. The
result of each open call is a new console unit. AmigaDOS and
Intuition see to it that only one window is the currently active
one, and its console, if any, is the only one (with a few excep-
tions) that receives notification of input events, such as keys-
trokes. Later in this chapter you'll see that other Intuition
events can be sensed by the console device as well.
NOTE: For this entire chapter the characters "<CSI>" represent
the Control Sequence Introducer. For output you may either use
the two-character sequence "<Esc>[" or the one-byte value $9B
(hex). For input you will receive $9B's.
1.2. SYSTEM FUNCTIONS
The various system functions, such as DoIO(), SendIO(), Abor-
tIO(), CheckIO() and so on operate normally. The only caveats
are that the CMD_WRITE may cause the caller to wait internally,
even with SendIO(), and a task waiting on response from a console
is at the user's whim. If a user never reselects that window,
and the console response provides the only wakeup-call, that task
may well sleep indefinitely.
November 17, 1985
- 2 -
1.3. CONSOLE I/O
The console device may be thought of as a kind of a terminal.
You send a character stream to the console device. You also
receive a character stream from the console device. These
streams may be characters or special sequences.
Console character screen output (as compared to console command
sequence transmission) outputs all standard printable characters
(character values hex 20 thru 7E and A0 thru FF) normally. Many
control characters such as BACKSPACE and RETURN are translated
into their exact ANSI equivalent actions. The line-feed charac-
ter is a bit different, in that it can be translated into a new-
line character. The net effect is that the cursor moves to the
first column of the next line whenever a <LF> is displayed. This
is set via the mode control sequences discussed under "Control
Sequences for Screen Output".
If you read from the console device, the keyboard inputs are
preprocessed for you. You will get the ASCII characters such as
"B". Most normal text gathering programs will read from the con-
sole device in this manner. Special programs like word proces-
sors and music keyboard programs will use raw input. Keys are
converted via the keymap associated with the unit.
The sections below deal with the following topics:
o Setting up for console I/O (creating an I/O request
structure)
o Writing to the console to control its behavior
o Reading from the console
o Closing down a console device
This section shows you how to set up for console I/O.
1.4. CREATING AN I/O REQUEST
Console I/O, like other devices, requires that you create an I/O
request message that you pass to the console device for process-
ing. The message contains the command, as well as a data area.
In the data area, for a write, there will be a pointer to the
stream of information you wish to write to the console. For a
read, this data pointer shows where the console is to copy the
data it has for you. There is also a length field that says how
many characters (maximum) are to be copied either from or to the
console device.
November 17, 1985
- 3 -
Here is a program fragment that can be used to create the message
block that you use for console communications.
For writing to the console:
struct IOStdReq *consoleWriteMsg; /* I/O request block pointer */
struct Port *consoleWritePort; /* a port at which to receive replies*/
consoleWritePort = CreatePort("mycon.write",0);
if(consoleWritePort == 0) exit(100); /* error in createport */
consoleWriteMsg = CreateStdIO(consoleWritePort);
if(consoleWriteMsg == 0) exit(200); /* error in createstdio */
For reading from the console:
struct IOStdReq *consoleReadMsg;
/* I/O request block pointer */
struct Port *consoleReadPort;
/* a port at which to receive replies */
consoleReadPort = CreatePort("mycon.read",0);
if(consoleReadPort == 0) exit(300); /* error in createport */
consoleReadMsg = CreateStdIO(consoleReadPort);
if(consoleReadMsg == 0) exit(400); /* error in createstdio */
These fragments show two messages and ports being set up. You
would use this if you want to have a read command continuously
queued up while using a separate message with its associated port
to send control command sequences to the console.
In addition, if you want to queue up multiple commands to the
console, you may wish to create multiple messages (but probably
just one port for receiving replied messages from the device).
1.5. OPENING A CONSOLE DEVICE
For other devices, you normally use OpenDevice() to pass an unin-
itialized IORequest block to the device. For a console device,
this is slightly different. You must have initialized two fields
in the request block; namely, the data pointer and the length
field. Here is a subroutine that can be used to open a console
device (attach it to an existing window). It assumes that
intuition.library is already open, a window has also been opened,
and this new console is to be attached to the open window.
November 17, 1985
- 4 -
/* this function returns a value of 0 if the console
* device opened correctly and a nonzero value (the error
* returned from OpenDevice) if there was an error.
*/
OpenConsole(request,window)
struct IOStdReq *request;
struct Window *window;
{
/* Open a console device */
request->io_Data = (char *) window;
request->io_Length = sizeof(*window);
return(OpenDevice("console.device", 0, request, 0));
}
To perform console I/O, you fill in fields of the console I/O
standard request, and pass this block to the console device using
one of the normal I/O functions. When the console device has
completed the action, the device returns the message block to the
port you have designated within the message itself. The function
CreateStdIO() initializes the message to contain the address of
the ReplyPort.
Here are subroutines that uses the IOStdReq created above. Note
that the IOStdReq itself contains a pointer to the device with
which it is communicating so a single function can be used to
communicate with multiple consoles.
November 17, 1985
- 5 -
/* output a single character to a specified console */
ConPutChar(request,character)
struct IOStdReq *request;
char character;
{
request->io_Command = CMD_WRITE;
request->io_Data = &character;
request->io_Length = 1;
DoIO(request);
return;
}
/* output a stream of known length to a console */
ConWrite(request,string,length)
struct IOStdReq *request;
char *string;
int length;
{
request->io_Command = CMD_WRITE;
request->io_Data = string;
request->io_Length = length;
DoIO(request);
return;
}
/* output a NULL-terminated string of characters to a console */
ConPutStr(request,string)
struct IOStdReq *request;
char *string;
{
request->io_Command = CMD_WRITE;
request->io_Data = string;
request->io_Length = -1; /* tells console to end when it
* sees a terminating zero on
* the string. */
DoIO(request);
return;
}
1.6. CONTROL SEQUENCES FOR SCREEN OUTPUT
Here is a list of the functions that the console device supports,
along with the character stream that you must send to the console
to produce the effect. Where the function table indicates multi-
ple characters, it is more efficient to use the ConWrite() func-
tion rather than ConPutChar() since it avoids the overhead of
transfering the message block multiple times. The table below
uses the second form of <CSI>, that is, the hex value 9B, to
November 17, 1985
- 6 -
minimize the number of characters to be transmitted to produce a
function.
In the table below, if an item is enclosed in square brackets, it
is an optional item and may be omitted. For example, for INSERT
[N] CHARACTERS, the value for N or M is shown as optional. The
console device responds to such optional items by treating the
value of N as if it is not specified.
The value of N or M is always a decimal number, having one or
more ASCII digits to express its value.
Table 1-1: Console Control Sequences
COMMAND SEQUENCE OF CHARACTERS (in hexadecimal)
BACKSPACE (move left one column) 08
LINE FEED (move down one text line 0A
as specified by the mode
function below)
VERTICAL TAB (move up one text line) 0B
FORM FEED (clear the console's screen) 0C
CARRIAGE RETURN (move to first column) 0D
SHIFT IN (undo SHIFT OUT) OE
SHIFT OUT (set MSB of each character 0F
before displaying)
ESC (escape; can be part of the control 1B
sequence introducer)
CSI (control sequence introducer) ESC [
RESET TO INITIAL STATE 9B 63
INSERT [N] CHARACTERS 9B [N] 40
(Inserts one or more spaces, shifting the
remainder of the line to the right.)
CURSOR UP [N] CHARACTER POSITIONS 9B [N] 41
(default = 1)
CURSOR DOWN [N] CHARACTER POSITIONS 9B [N] 42
(default = 1)
CURSOR FORWARD [N] CHARACTER POSITIONS 9B [N] 43
(default = 1)
CURSOR BACKWARD [N] CHARACTER 9B [N] 44
POSITIONS (default = 1)
CURSOR NEXT LINE [N] (to column 1) 9B [N] 45
CURSOR PRECEDING LINE [N] 9B [N] 46
(to column 1)
MOVE CURSOR TO ROW; COLUMN 9B [N] [3B N] 48
where N is row, M is column, and
semicolon (hex 3B) must be present
as a separator, or if row is left
out, so the console device can tell
that the number after the semicolon
actually represents the column number.
ERASE TO END OF DISPLAY 9B 4A
ERASE TO END OF LINE 9B 4B
November 17, 1985
- 7 -
INSERT LINE (above the line containing 9B 4C
the cursor)
DELETE LINE (remove current line, move 9B 4D
all lines up one position to fill
gap, blank bottom line)
DELETE CHARACTER [N] (that cursor is 9B [N] 50
sitting on and to the right if
[N] is specified)
SCROLL UP [N] LINES (Remove line(s) from 9B [N] 53
top of screen, move all other lines
down, blanks [N] bottom lines).
SCROLL DOWN [N] LINES (Remove line(s) 9B [N] 54
from bottom of screen, move all
other lines up, blanks [N] top lines).
SET MODE (cause LINEFEED to respond as 9B 32 30 68
RETURN-LINEFEED)
RESET MODE (cause LINEFEED to respond 9B 32 30 6C
only as LINEFEED)
DEVICE STATUS REPORT (cause console to 9B 6E
insert into your read-stream a CURSOR
POSITION REPORT; see "Reading from
the Console" for more info).
SELECT GRAPHIC RENDITION See note below. [S];[F];[B]
(select text style, foreground color,
background color)
NOTE: For SELECT GRAPHIC RENDITION, any number of
parameters, in any order, are valid. They are
separated by semicolons.
<style> =
0 plain text
1 bold-face
3 italic
4 underscore
7 inverse-video
<fg> =
30 - 37 selecting system colors 0-7 for foreground
transmitted as two ASCII characters
<bg> =
40 - 47 selecting system colors 0-7 for background
transmitted as two ASCII characters
For example, to select bold-face, with color 3 as
foreground and color 0 as background, send the
sequence:
9B 31 3B 33 33 3B 34 30 6D
November 17, 1985
- 8 -
representing the ASCII sequence:
"<CSI>1;33;40m"
where <CSI> is the control sequence introducer, here
used as the single-character value 9B hex.
The following are not ANSI standard sequences; they are
private Amiga sequences.
In the four command descriptions that follow, length,
width, and offset are comprised of one or more ASCII
digits, defining a decimal value.
COMMAND SEQUENCE OF CHARACTERS (in hexadecimal)
SET PAGE LENGTH (in character raster lines,
causes console to recalculate,
using current font, how many text 9B <length> 74
lines will fit on the page.
SET LINE LENGTH (in character positions,
using current font, how many characters
should be placed on each line). 9B <width> 75
SET LEFT OFFSET (in raster columns, how far
from the left of the window
should the text begin). 9B <offset> 78
SET TOP OFFSET (in raster lines, how far
from the top of the window's
RastPort should the topmost
line of the character begin). 9B <offset> 79
NOTE: The console normally handles the above four
functions automatically. To allow it to do so again
after setting your own values, you can send the func-
tion without a parameter.
COMMAND SEQUENCE OF CHARACTERS (in hexadecimal)
SET RAW EVENTS-see the separate topic
"Selecting Raw Input Events"
below for more details.
RESET RAW EVENTS-see "Selecting Raw Input Events" below.
November 17, 1985
- 9 -
SET CURSOR RENDITION - make the cursor
visible or invisible:
invisible: 9B 30 70
visible: 9B 70
WINDOW STATUS REQUEST - ask the console
device to tell you the current
bounds of the window, in
upper and lower row and column
character positions.
(User may have resized or repositioned
it). See "Window Bounds Report" below. 9B 71
Examples
Move cursor right by 1:
Character string equivalents: <CSI>C or <CSI>1C
Numeric (hex) equivalents: 9B 43 9B 31 43
Move cursor right by 20:
Character string equivalent: <CSI>20C
Numeric (hex) equivalent: 9B 32 30 43
Move cursor to upper left corner (home):
Character string equivalents:
<CSI>H or
<CSI>1;1H or
<CSI>;1H or
<CSI>1;H
Numeric (hex) equivalents:
9B 48
9B 31 3B 31 48
9B 3B 31 48
9B 31 3B 48
Move cursor to the forth column of the first line of the window:
November 17, 1985
- 10 -
Character string equivalents:
<CSI>1;4H or
<CSI>;4H
Numeric (hex) equivalents:
9B 31 3B 34 48
9B 3B 34 48
Clear the screen:
Character string equivalents:
<FF> or CTRL-L {clear screen character} or
<CSI>H<CSI>J {home and clear to end of screen} or
Numeric (hex) equivalents:
0C
9B 48 9B 4A
Reading input from the console device returns an ANSI 3.64 stan-
dard byte stream. This stream may contain normal characters
and/or RAW input event information. You may also request other
RAW input events using the SET RAW EVENTS and RESET RAW EVENTS
control sequences discussed below. See "Selection of Raw Input
Events".
The following subroutines are useful for setting up for console
reads. Only a single-character-at-a-time version is shown here.
NOTE: This example does not illustrate the fact that a request
for more than one character can be satisfied by only one, thus
requiring you to look at io_actual.
/* queue up a read request to a console, show where to
* put the character when ready to be returned. Most
* efficient if this is called right after console is
* opened */
QueueRead(request,whereto)
struct IOStdReq *request;
char *whereto;
{
request->io_Command = CMD_READ;
request->io_Data = whereto;
request->io_Length = 1;
SendIO(request);
return;
}
November 17, 1985
- 11 -
/* see if there is a character to read. If none, don't wait,
* come back with a value of -1 */
int
ConMayGetChar(consolePort,request,whereto)
struct Port *consolePort
struct IOStdReq *request;
char *whereto;
{
register temp;
if ( GetMsg(consolePort) == NULL ) return(-1);
temp = *whereto;
QueueRead(request,whereto);
return(temp);
}
/* go and get a character; put the task to sleep if
* there isn't one present */
UBYTE
ConGetChar(consolePort,request,whereto)
struct IOStdReq *request;
struct Port *consolePort;
char *whereto;
{
register temp;
while((GetMsg(consolePort) == NULL)) WaitPort(consolePort);
temp = *whereto; /* get the character */
QueueRead(request,whereto);
return(temp);
}
For the most part, keys whose keycaps are labeled with ANSI stan-
dard characters will ordinarily be translated into their ASCII
equivalent character by the console device through the use of its
keymap. A separate section in this chapter has been dedicated to
the method used to establish a keymap and the internal organiza-
tion of the keymap.
For keys other than those with normal ASCII equivalents, an
escape sequence is generated and inserted into your input stream.
For example, in the default state (no raw input events selected)
the function and arrow keys will cause the following sequences to
be inserted in the input stream:
November 17, 1985
- 12 -
Table 1-2: Special Key Report Sequences
center box; c c l.
KEY UNSHIFTED SENDS SHIFTED SENDS
F1 <CSI>0~ <CSI>10~ F2 <CSI>1~ <CSI>11~
F3 <CSI>2~ <CSI>12~ F4 <CSI>3~ <CSI>13~
F5 <CSI>4~ <CSI>14~ F6 <CSI>5~ <CSI>15~
F7 <CSI>6~ <CSI>16~ F8 <CSI>7~ <CSI>17~
F9 <CSI>8~ <CSI>18~ F10 <CSI>9~ <CSI>19~
HELP <CSI>?~ <CSI>?~ (same)
Arrow keys:
Up <CSI>A <CSI>T~ Down <CSI>B <CSI>S~
Left <CSI>C <CSI> A~ (notice the space)
Right <CSI>D <CSI> @~ (notice the space)
If you have sent the DEVICE STATUS REPORT command sequence, the
console device returns a cursor position report into your input
stream. It takes the form:
<CSI><row>;<column>R
For example, if the cursor is at column 40, and row 12, here are
the ASCII values you receive in a stream:
9B 34 30 3B 31 32 52
A user may have either moved or resized the window to which your
console is bound. By issuing a WINDOW STATUS REPORT to the con-
sole, you can read the current position and size in the input
stream. This window bounds report takes the following form:
<CSI>1;1;<bottom margin>;<right margin>r
Note that the top and left margins are always 11 for the Amiga.
The bottom and right margins give you the window row and column
dimensions as well. For a window that holds 20 lines with 60
characters per line, you will receive the following in the input
stream:
9B 31 3B 31 3B 32 30 3B 36 30 73
November 17, 1985
- 13 -
If the keyboard information, including "cooked" keystrokes does
not give you enough information about input events you can
request additional information from the console driver.
The command to SET RAW EVENTS is formatted as:
"<CSI>[event-types-separated-by-semicolons]{"
If, for example, you need to know when each key is pressed and
released you would request "RAW keyboard input". This is done by
writing "<CSI>1{" to the console. In a single SET RAW EVENTS
request, you can ask the console to setup for multiple event
types at one time. You must send multiple numeric parameters,
separating them by semicolons (;). Example: ask for gadget
pressed, gadget released and close gadget events - write:
"<CSI>7;8;11{" (all as ASCII characters, without the quotes).
You can reset, that is, delete from reporting, one or more of the
raw input event types by using the RESET RAW EVENTS command, in
the same manner as the SET RAW EVENTS was used to establish them
in the first place. This command stream is formatted as:
<CSI>[event-types-separated-by-semicolons]}
So, for example, you could reset all of the events set in the
above example by transmitting the command sequence:
"<CSI>7;8;11}" Here is a list of the valid raw input event types:
Table 1-3: Raw Input Event Types
REQUEST NUMBER DESCRIPTION
0 nop Used internally.
1 RAW keyboard input. Intuition swallows all by the select
button.
2 RAW mouse input
3 Event Sent whenever your window is made active.
4 Pointer position
5 (unused)
6 Timer
7 Gadget pressed
8 Gadget released
9 Requester activity
10 Menu numbers
11 Close Gadget
12 Window resized
13 Window refreshed
14 Preferences changed (not yet implemented)
15 Disk removed
16 Disk inserted
November 17, 1985
- 14 -
1.7. COMPLEX INPUT EVENT REPORTS
If you select any of these events you will start to get informa-
tion about the events in the following form:
<CSI><class>;<subclass>;<keycode>;<qualifiers>;<x>;<y>;
<seconds>;<microseconds>|
where:
<CSI>
is a one-byte field. It is the "control sequence intro-
ducer", 9B in hex.
<class>
is the RAW input event type, from the above table.
<subclass>
is usually 0. If the mouse is moved to the right controller,
this would be 1.
<keycode>
indicates which key number was pressed (see figure 4-1 and
table 4-5). This field can also be used for mouse informa-
tion.
<qualifiers>
indicates the state of the keyboard and system. The qualif-
iers are defined as follows:
November 17, 1985
- 15 -
Table 1-4: Input Event Qualifiers
BIT MASK KEY
0 0001 left shift
1 0002 right shift
2 0004 capslock *Associated keycode is
special; see below.
3 0008 control
4 0010 left ALT
5 0020 right ALT
6 0040 left Amiga key pressed
7 0080 right Amiga key pressed
8 0100 numeric pad
9 0200 repeat
10 0400 interrupt Not currently used.
11 0800 multi broadcast This window (active one)
or all windows.
12 1000 left mouse button
13 2000 right mouse button
14 4000 middle mouse button (Not available on
standard mouse.)
15 8000 relative mouse Indicates mouse coordinates
are relative, not absolute.
The CAPS LOCK key is handled in a special manner. It only gen-
erates a keycode when it is pressed, not when it is released.
However the up/down bit (80 hex) is still used and reported. If
pressing the caps lock key causes the LED to light then key code
62 (caps lock pressed) is sent. If pressing the caps lock key
extinguishes the LED then key code 190 (caps lock released) is
sent. In effect, the keyboard reports this key as held down
until it is struck again.
The <x> and <y> fields are filled by some classes with an Intui-
tion address: x<<16+y.
The <seconds> and <microseconds> fields contain the system time
stamp taken at the time the event occurred. These values are
stored as long-words by the system.
With RAW keyboard input selected, keys will no longer return a
simple one-character "A" to "Z" but will rather return raw key-
code reports of the form:
<CSI>1;0;<keycode>;<qualifiers>;0;0;<seconds>;<microseconds>|
For example, if the user pressed and released the "B" key with
the left shift and right Amiga keys also pressed you might
receive the following data:
November 17, 1985
- 16 -
<CSI>1;0;35;129;0;0;23987;99|
<CSI>1;0;163;129;0;0;24003;18|
The <keycode> field is an ASCII decimal value representing the
key pressed or released. Adding 128 to the pressed key code will
result in the released keycode. Figure 4-1 lets you convert
quickly from a key to its keycode. The tables let you convert
quickly from a keycode to a key.
Figure 1-1: The Amiga Keyboard, Showing Keycodes in Hex
The default values given correspond to:
1) The values the console device will return when these keys
are pressed, and
2) The Keycaps as shipped with the standard American key-
board.
November 17, 1985
- 17 -
Table 1-5: System Default Console Key Mapping
RAW UNSHIFTED SHIFTED
KEY KEYCAP DEFAULT DEFAULT NUMBER LEGEND VALUE VALUE
00 ` ~ ` (Accent grave) ~ (tilde)
01 1 ! 1 !
02 2 @ 2 @
03 3 # 3 #
04 4 $ 4 $
05 5 % 5 %
06 6 ^ 6 ^
07 7 & 7 &
08 8 * 8 *
09 9 ( 9 (
0A 0 ) 0 )
0B - _ - (Hyphen) _ (Underscore)
0C = + = +
0D \\ | \\ |
0E (undefined)
0F 0 0 0 (Numeric pad)
10 Q q Q
11 W w W
12 E e E
13 R r R
14 T t T
15 Y y Y
16 U u U
17 I i I
18 O o O
19 P p P
1A [{ [ {
1B ] } ] }
1C (undefined)
1D 1 1 1 (Numeric pad)
1E 2 2 2 (Numeric pad)
1F 3 3 3 (Numeric pad)
20 A a A 21 S s S
22 D d D 23 F f F
24 G g G 25 H h H
26 J j J 27 K k K
28 L l L
29 ; : ; :
2A ' " ' (single quote) "
2B (RESERVED) (RESERVED)
2C (undefined)
2D 4 4 4 (Numeric pad)
2E 5 5 5 (Numeric pad)
2F 6 6 6 (Numeric pad)
30 (RESERVED) (RESERVED)
31 Z z Z
32 X x X
33 C c C
34 V v V
35 B b B
36 N n N
37 M m M
38 , < , (comma) <
39 . > . (period) >
3A / ? / ?
3B (undefined)
3C . . . (Numeric pad)
3D 7 7 7 (Numeric pad)
3E 8 8 8 (Numeric pad)
3F 9 9 9 (Numeric pad)
40 (Space bar) 20 20
41 BACKSPACE 08 08
42 TAB 09 09
43 ENTER 0D 0D (Numeric pad)
44 RETURN 0D 0D
45 ESC 1B 1B
46 DEL 7F 7F
47 (undefined)
November 17, 1985
- 18 -
48 (undefined)
49 (undefined)
4A - - - (Numeric Pad)
4B (undefined)
4C Up Arrow <CSI>A~ <CSI>T~
4D Down Arrow <CSI>B~ <CSI>S~
4E Forward Arrow <CSI>C~ <CSI> A~ [1]
4F Backward Arrow <CSI>D~ <CSI> @~
_________________________
[1] In shifted Forward Arrow and Backward arrow, note
blank space after <CSI>.
November 17, 1985
- 19 -
RAW UNSHIFTED SHIFTED
KEY KEYCAP DEFAULT DEFAULT NUMBER LEGEND VALUE VALUE
50 F1 <CSI>0~ <CSI>10~
51 F2 <CSI>1~ <CSI>11~
52 F3 <CSI>2~ <CSI>12~
53 F4 <CSI>3~ <CSI>13~
54 F5 <CSI>4~ <CSI>14~
55 F6 <CSI>5~ <CSI>15~
56 F7 <CSI>6~ <CSI>16~
57 F8 <CSI>7~ <CSI>17~
58 F9 <CSI>8~ <CSI>18~
59 F10 <CSI>9~ <CSI>19~
5A (undefined)
5B (undefined)
5C (undefined)
5D (undefined)
5E (undefined)
5F HELP <CSI>?~ <CSI>?~
November 17, 1985
- 20 -
KEY KEYCAP NUMBER LEGEND
60 SHIFT (left of space bar)
61 SHIFT (right of space bar)
62 CAPS LOCK
63 CTRL
64 (Left) ALT
65 (Right) ALT
66 Amiga (left of space bar) Close Amiga
67 Amiga (right of space bar) Open Amiga
68 Left mouse button Inputs are only for the
one (not converted) mouse connected to Intuition
69 Right mouse button currently "gameport"
one. (not converted)
6A Middle mouse button (not converted)
6B (undefined)
6C (undefined)
6D (undefined)
6E (undefined)
6F (undefined)
November 17, 1985
- 21 -
center; l10 l. RAW KEY NUMBER FUNCTION
70-7F (undefined)
80-F8 Up transition (release or unpress key of one
of the above keys). 80 for 00, F8 for 7F.
F9 Last keycode was bad (was sent in order to
resynchronize).
FA Keyboard buffer overflow.
FB (undefined, reserved for keyboard processor
catastrophe)
FC Keyboard selftest failed.
FD Power-up key stream start. Keys pressed or
stuck at power-up will be sent between FD and FE.
FE Power-up key stream end.
FF (undefined, reserved)
FF Mouse event, movement only, no button change.
(not converted)
Notes about the preceding table:
1) "(undefined)" indicates that the current keyboard design
should not generate this number. If you are using Set-
KeyMap() to change the key map the entries for these
numbers must still be included.
2) "(not converted)" refers to mouse button events. You
must use the sequence "<CSI>2{" to inform the console
driver that you wish to receive mouse events; otherwise
these will not be transmitted.
3) "(RESERVED)" Indicates that these keycodes have been
reserved for non-US keyboards. The "2B" code key will be
between the double-quote(") and RETURN keys. The "30"
code key will be between the SHIFT and "Z" keys.
1.8. KEYMAPPING
The Amiga has the capability of mapping the keyboard in any
manner that you wish. In other computers, this capability is
normally provided through the use of "keyboard enhancers". In
the Amiga, however, the capability is already present and the
vectors that control the remapping are user accessible.
The functions called GetKeyMap() and SetKeyMap() each deal with a
set of 8 longword pointers, known as the KeyMap data structure.
The KeyMap data structure is shown below.
November 17, 1985
- 22 -
struct KeyMap {
APTR km_LoKeyMapTypes;
APTR km_LoKeyMap;
APTR km_LoCapsable;
APTR km_LoRepeatable;
APTR km_HiKeyMapTypes;
APTR km_HiKeyMap;
APTR km_HiCapsable;
APTR km_HiRepeatable;
};
GetKeyMap() returns a pointer to this table of pointers, showing
where in memory each of the tables representing the keymapping
may be found.
As a prelude to the following material, note that the Amiga key-
board transmits raw key information to the computer in the form
of a key position and a transition. Figure 4-1 shows a physical
layout of the keys and the hexadecimal number that is transmitted
to the system when a key is pressed. When the key is released,
its value, plus hexadecimal 80, is transmitted to the computer.
The key mapping described herein refers to the translation from
this raw key transmission into console device output to the user.
The low key map provides translation of the key values from hex
00-3F; the high key map provides translation of key value from
hex 40-67.
Raw output from the keyboard for the LoKeyMap does not include
the space bar, TAB, ALT, CTRL, arrow keys and several other keys
(shown in HiKeyMap, below).
Figure 1-2: Low Key Map Translation Table
November 17, 1985
- 23 -
Table 1-6: High Key Map Hex Values
40 Space
41 Backspace
42 Tab
43 Enter
44 Return
45 Escape
46 Delete
4A Numeric Pad
4C Cursor Up
4D Cursor Down
4E Cursor Forward
4F Cursor Backward
50-59 Function keys F1-F10
5F Help
60 Left Shift
61 Right Shift
62 Caps Lock
63 Control
64 Left Alt
65 Right Alt
66 Left Amiga
67 Right Amiga
The keymap table for the low and high keymaps consists of 4-byte
entries, one per hex keycode. These entries are interpreted in
one of two possible ways:
a. as 4 separate bytes, specifying how the key is to be
interpreted when pressed:
o alone
o with one qualifier
o with another qualifier
o with both qualifiers
where a qualifier is one of three possible keys:
o CTRL (control)
o ALT
o SHIFT
b. as a longword containing the address of a string descrip-
tor, where a string of hex digits is to be output when
this key is pressed. If a string is to be output, any
combination of qualifiers may affect the string that may
be transmitted.
NOTE: The keymap table must begin aligned on a word boundary.
Each entry is 4-bytes long, thereby maintaining word alignment
throughout the table. This is necessary since some of the
entries may be longword addresses and must be aligned properly
for the 68000.
As you may have noticed, there are three possible qualifiers, but
only a 4-byte space in the table for each key. This does not
allow space to describe what the computer should output for all
possible combinations of qualifiers. This problem is solved by
November 17, 1985
- 24 -
only allowing all three qualifiers to affect the output at the
same time in string mode. Here is how that works.
For "vanilla" keys, such as the alphabetic keys, use the 4 bytes
to represent the data output for the key alone, shifted key,
ALT'ed key, and shifted-and-ALT'ed key. Then for the CTRL-key-
plus-vanilla-key, use the code for the key alone with bits 6 and
5 set to 0.
For other keys, such as the return key or escape key, the qualif-
iers specified in the keytypes table (up to two) are the qualif-
iers used to establish the response to the key. This is done as
follows. In the keytypes table, the values listed for the key
types are those listed for the qualifiers in keymap.h and
keymap.i. Specifically, these qualifier equates are:
KC_NOQUAL 0x00
KCF_SHIFT 0x01
KCF_ALT 0x02
KCF_CONTROL 0x04
KC_VANILLA 0x07
KCF_DOWNUP 0x08
KCF_STRING 0x40
As shown above, the qualifiers for the various types of keys
occupy specific bit positions in the key types control byte.
A keymap table entry looks like this, in assembly code:
SOME_KEY:
DC.B VALUE_1, VALUE_2, VALUE_3, VALUE_4
Here is how you interpret the keymap for various combinations of
the qualifier bits:
November 17, 1985
- 25 -
Table 1-7: Keymap Qualifier Bits
If Keytype is: Then value in this position in the
keytable is out put when the key is
pressed along with:
KC_NOQUAL - - - alone
KCF_SHIFT - - SHIFT alone
KCF_ALT - - ALT alone
KCF_CONTROL - - CTRL alone
KCF_ALT+KCF_SHIFT SHIFT+ALT ALT SHIFT alone
KCF_CONTROL+KCF_ALT CTRL+ALT CTRL ALT alone
KCF_CONTROL+KCF_SHIFT CTRL+SHIFT CTRL SHIFT alone
KC_VANILLA SHIFT+ALT ALT SHIFT alone*
* special case-CTRL key, when pressed with one of the al-
phabet keys and certain others, is to output key-alone
value with the bits 6 and 5 set to zero.
The vectors named km_LoKeyTypes and km_HiKeyTypes contain one
byte per raw key code. This byte defines the entry type that is
made in the key table by a set of bit positions.
Possible key types are:
o any of the qualifier groupings noted above, or
o KCF_STRING + any combination of KCF_SHIFT, KCF_ALT,
KCF_CONTROL (or KC_NOQUAL) if the result of pressing the
key is to be a stream of bytes (and key-with-one-or-
more-qualifiers is to be one or more alternate streams of
bytes).
Any key can be made to output up to 8 unique byte streams
if KCF_STRING is set in its keytype. The only limitation
is that the total length of all of the strings assigned
to a key be within the "jump range" of a single byte
increment. See the "String-Output Keys" section below
for more information.
The low keytype table covers the raw keycodes from hex 00-3F, and
contains one byte per keycode. Therefore this table contains 64
(decimal) bytes. The high keytype table covers the raw keycodes
from hex 40-67, and contains 38 (decimal) bytes.
When a key is to output a string, the keymap table contains the
address of a string descriptor in place of a 4-byte mapping of a
key as shown above. Here is a partial table for a new high key
map table which contains only three entries thus far. The first
November 17, 1985
- 26 -
two are for the space bar and the backspace key; the third is for
the tab key, which is to output a string that says "[TAB]". An
alternate string, "[SHIFTED-TAB]", is also to be output when a
shifted TAB key is pressed.
Table 1-8: Composing an Alternate Key Map
newHiMapTypes:
DC.B KCF_ALT,KC_NOQUAL,
DC.B KCF_STRING+KCF_SHIFT, ... ;(more)
newHiMap:
DC.B 0,0,$A0,$20 ;space bar, and ALT-space bar
DC.B 0,0,0,$08 ;BACKSPACE key only
DC.L newkey42 ;new definition for string to
;output for TAB key ... ;(more)
newkey42:
DC.B new42ue - new42us ;length of the
;unshifted string
DC.B new42us - newkey42
;number of bytes from start of
;string descriptor to start of
;this string
DC.B new42se - new42ss ;length of the shifted string
DC.B new42ss - newkey42
;number of bytes from start of
;string descriptor to start of
;this string
new42us:
DC.B '[TAB]'
new42ue:
new42ss:
DC.B '[SHIFTED-TAB]'
new42se:
The new high map table points to the string descriptor at address
newkey42. The new high map types table says that there is one
qualifier, which means that there are two strings in the key
string descriptor.
Each string in the descriptor takes two bytes in this part of the
table; the first byte is the length of the string, the second
byte is the distance from the start of the descriptor to the
start of the string. Therefore, a single string (KCF_STRING +
KC_NOQUAL) takes 2 bytes of string descriptor. If there is one
qualifier, 4 bytes of descriptor are used. If there are two
qualifiers, 8 bytes of descriptor are used. If there are 3 qual-
ifiers, 16 bytes of descriptor are used. All strings start
immediately following the string descriptor in that they are
November 17, 1985
- 27 -
accessed as single byte offsets from the start of the descriptor
itself. Therefore, the distance from the start of the descriptor
to the last string in the set (the one that uses the entire set
of specified qualifiers) must start within 255 bytes of the
descriptor address.
Since the length of the string is contained in a single byte, the
length of any single string must be 255 bytes or less while also
meeting the "reach" requirement.
The length of a keymap containing string descriptors and strings
is variable and depends on the number and size of the strings
that you provide.
The vectors called km_LoCapsable and km_HiCapsable point to the
first byte in an 8-byte table that contains more information
about the keytable entries.
Specifically, if the CAPS LOCK key has been pressed the CAPS LOCK
LED is on), and if there is a bit on in that position in the
capsable map, then this key will be treated as though the shift-
key is now currently pressed. For example, in the default key
mapping, the alphabetic keys are "capsable" but the punctuation
keys are not. This allows you to set the shift-lock, just as on
a normal typewriter, and get all capital letters. However,
unlike a normal typewriter, you need not go out of shift-lock to
correctly type the punctuation symbols or numeric keys.
In the table, the bits that control this feature are numbered
from the lowest bit in the byte, and from the lowest memory byte
address to the highest. For example, the bit representing caps-
able status for the key that transmits raw code 00 is bit 0 in
byte 0; for the key that transmits raw code 08 it's bit 0 in byte
1, and so on.
There are 64 bits (8-bytes) in each of the two capsable tables.
For both the low and high key maps there is an 8-byte table that
provides one bit per possible raw key code. This bit indicates
whether or not the specified key should repeat at the rate set by
the Preferences program. The bit positions correspond to those
specified in the capsable bit table.
If there is a 1 in a specific position, the key can repeat. The
vectors that point to these tables are called km_LoRepeatable and
km_HiRepeatable.
In the default low key map, all of the keys are treated in the
same manner. That is:
o When pressed alone, they transmit the ASCII equivalent of
November 17, 1985
- 28 -
the unshifted key.
o When shifted, they translate the ASCII equivalent of the
shifted value when printed on the keycap.
o When "ALT'ed" (pressed along with an ALT key), they
transmit the alone-value with the high bit of a byte set
(value plus hex 80).
When shifted and ALT'ed, they transmit the shifted-value
plus hex 80.
In this table, the bytes that describe the data to be transmitted
are positioned as the example for the "A" key shown here:
center; l l l l.
key_A DC.B ('A')+$80 ;shifted and ALT'ed
DC.B ('a')+$80 ;ALT'ed only
DC.B ('A') ;shifted only
DC.B ('a') ;not shifted or ALT'ed.
In addition to the response to the key alone, shifted, ALT'ed and
shifted-and-ALT'ed, the default low keymap also responds to the
key combination of "CTRL + key" by stripping off bits 6 and 5 of
the generated data byte. For example, CTRL + A generates the
translated keycode 01 (61 with bits 6 and 5 set to 0).
All keys in the low key map are mapped to their ASCII equivalents
as noted in the low key map key table shown above.
Since the low key table contains 4 bytes per key, and describes
the keys (raw codes) from hex 00-3F, there are 64 times 4 or 256
bytes in this table.
Most of the keys in the high key map generate strings rather than
single character mapping. The following keys map characters with
no qualifier, along with their byte mapping:
KEY GENERATES VALUE:
BACKSP $08 ENTER $0D DEL $7F
November 17, 1985
- 29 -
The following keys map characters and use a single qualifier:
KEY GENERATES VALUE: IF USED WITH QUALIFIER,
GENERATES VALUE:
SPACE $20 $A0 (qualifier = ALT)
RETURN $0D $0A (qualifier = CONTROL)
ESC $1B $9B (qualifier = ALT)
numeric pad '-' $2D $FF (qualifier = ALT)
The following keys generate strings:
KEY GENERATES VALUE: IF USED WITH <SHIFT>,
GENERATES VALUE:
TAB $09 $9B, followed by 'Z'
cursor:
UP $9B, followed by 'A' $9B, followed by 'T'
DOWN $9B, followed by 'B' $9B, followed by 'S'
FWD $9B, followed by 'C' $9B, followed by ' ',
followed by '@'
BACKWD $9B, followed by 'D' $9B, followed by ' ',
followed by 'A'
function keys:
F1 $9B, followed by '0~' $9B, followed by '10~'
F2 $9B, followed by '1~' $9B, followed by '11~'
F3 $9B, followed by '2~' $9B, followed by '12~'
F4 $9B, followed by '3~' $9B, followed by '13~'
F5 $9B, followed by '4~' $9B, followed by '14~'
F6 $9B, followed by '5~' $9B, followed by '15~'
F7 $9B, followed by '6~' $9B, followed by '16~'
F8 $9B, followed by '7~' $9B, followed by '17~'
F9 $9B, followed by '8~' $9B, followed by '18~'
F10 $9B, followed by '9~' $9B, followed by '19~'
HELP $9B, followed by '?~' (no qualifier used)
November 17, 1985
- 30 -
1.9. CLOSING A CONSOLE DEVICE
When you have finished using a console, it must be closed so that
the memory areas it utilized may be returned to the system memory
manager. Here is a sequence that you can use to close a console
device:
CloseDevice(requestBlock);
Note that you should also delete the messages and ports associ-
ated with this console after the console has been closed:
DeleteStdIO(consoleWriteMsg);
DeleteStdIO(consoleReadMsg);
DeletePort(consoleWritePort);
DeletePort(consoleReadPort);
If you have finished with the window used for the console device,
you can now close it.
November 17, 1985
